home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr48 / btv115.zip / BTV.TXT < prev    next >
Text File  |  1993-04-01  |  62KB  |  1,500 lines
  1. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  2. ──────────────────────────────────────────────────────────────────────────────
  3. INTRODUCTION
  4.  
  5. BTV.PAS is a fully object oriented Turbo Pascal 6.0 programming interface for
  6. Novell's Btrieve database manager. Through OOP techniques BTV.PAS greatly
  7. simplifies interface to Btrieve for Turbo Pascal. Included in this package
  8. are full working examples that demonstrate the ease and power of the BTV
  9. interface. Also included is a complete application for recovering damaged
  10. files.
  11.  
  12. Just a few of the features are :
  13.  
  14.  * Over 40 functions for Btrieve including :
  15.  * Create, easy file definition and creation
  16.  * Clone, create an empty copy of a file
  17.  * Recover, recover records from a damaged file
  18.  * Save, save all records to a DOS file compatible with BUTIL
  19.  * Load, read records from a file created by Save or BUTIL
  20.  * Create Supplemental Indexes
  21.  * Supports multiple and segmented keys
  22.  * Supports alternate collating sequences
  23.  * Supports variable length records
  24.  * Automatic padding and justification of string keys
  25.  * Supports full transaction processing
  26.  * Supports full network record and file locking
  27.  * Automatic integrated error handling
  28.  
  29. In writing this documentation I have assumed the reader is knowledgeable
  30. about the workings of Btrieve and the basics object oriented programming in
  31. Turbo Pascal 6.0. This document is not meant to explain or serve as a
  32. tutorial on either of these subjects. I think you will find the source code
  33. itself fairly well documented. I strongly recommend that you look it over.
  34. If you have any questions, suggestions for improvement, or problems, please
  35. do not hesitate to contact me. If you need a version for Turbo 5.5 please
  36. let me know.
  37.  
  38.     Richard Hansen
  39.     PO Box 18571
  40.     Saint Paul, MN  55118-0571  USA
  41.  
  42.     CompuServe ID 70242,3367
  43.  
  44.  
  45. BTV.PAS Copyright (C) 1992  Richard W. Hansen, all rights reserved.
  46. Btrieve Copyright (C) Novell, Inc.
  47. BUTIL Copyright (C) Novell, Inc.
  48.  
  49.  
  50. DEFINITION OF SHAREWARE
  51.  
  52. Shareware distribution gives users a chance to try software before buying it.
  53. If you try a Shareware program and continue using it, you are expected to
  54. register. Individual programs differ on details -- some request registration
  55. while others require it, some specify a maximum trial period. With
  56. registration, you get anything from the simple right to continue using the
  57. software to an updated program with printed manual.
  58.  
  59.  
  60.                                       1
  61. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  62. ──────────────────────────────────────────────────────────────────────────────
  63. Copyright laws apply to both Shareware and commercial software, and the
  64. copyright holder retains all rights, with a few specific exceptions as stated
  65. below. Shareware authors are accomplished programmers, just like commercial
  66. authors, and the programs are of comparable quality. (In both cases, there
  67. are good programs and bad ones!) The main difference is in the method of
  68. distribution. The author specifically grants the right to copy and distribute
  69. the software, either to all and sundry or to a specific group. For example,
  70. some authors require written permission before a commercial disk vendor may
  71. copy their Shareware.
  72.  
  73. Shareware is a distribution method, not a type of software. You should find
  74. software that suits your needs and pocketbook, whether it's commercial or
  75. Shareware. The Shareware system makes fitting your needs easier, because you
  76. can try before you buy. And because the overhead is low, prices are low also.
  77. Shareware has the ultimate money-back guarantee -- if you don't use the
  78. product, you don't pay for it.
  79.  
  80.  
  81. DISCLAIMER - AGREEMENT
  82.  
  83. Users of BTV.PAS must accept this disclaimer of warranty:  "BTV.PAS is
  84. supplied as is. The author disclaims all warranties, expressed or implied,
  85. including, without limitation, the warranties of merchantability and of
  86. fitness for any purpose. The author assumes no liability for damages, direct
  87. or consequential, which may result from the use of BTV.PAS."
  88.  
  89. BTV.PAS is "shareware" and is provided at no charge to the user for
  90. evaluation. Feel free to share it with your friends, but do not give it away
  91. altered or as part of any other source code package. If you find this source
  92. code useful and continue to use BTV.PAS after a reasonable trial period, you
  93. must register it. The registration fee will license one copy for use on any
  94. one computer at any one time. You must treat this software just like a book.
  95. An example is that this software may be used by any number of people and may
  96. be freely moved from one computer location to another, so long as there is no
  97. possibility of it being used at one location while it's being used at
  98. another. Just as a book cannot be read by two different persons at the same
  99. time.
  100.  
  101. Commercial users of BTV.PAS must register and pay for their copies of BTV.PAS
  102. within 30 days of first use or their license is withdrawn. You may use
  103. BTV.PAS in your software projects, but you may only distribute it in
  104. executable form. No royalties are required for programs you develop using
  105. licensed copies of BTV.PAS.
  106.  
  107. Anyone distributing BTV.PAS for any kind of remuneration must first contact
  108. Richard Hansen for authorization. This authorization will be automatically
  109. granted to distributors recognized by the ASP as adhering to its guidelines
  110. for shareware distributors, and such distributors may begin offering BTV.PAS
  111. immediately (However Richard Hansen must still be advised so that the
  112. distributor can be kept up-to-date with the latest version of BTV.PAS.).
  113.  
  114.  
  115. REGISTRATION
  116.  
  117. Many new features are planned, so registration is a good idea, just to make
  118. sure you have the latest and greatest version. Individual registrations are
  119.  
  120.                                       2
  121. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  122. ──────────────────────────────────────────────────────────────────────────────
  123. $20.00 (U.S), commercial and corporate registrations are $50.00 (U.S.). All
  124. non U.S. registrations please add $10.00. All registered users will receive a
  125. copy of the latest version and printed documentation.
  126.  
  127. Send all registrations to :
  128.  
  129.     Richard Hansen
  130.     PO Box 18571
  131.     Saint Paul, MN  55118-0571  USA
  132.  
  133.  
  134. OVERVIEW
  135.  
  136. There are three objects that make up the BTV OOP interface to Btrieve. The
  137. most important of these is the BtrieveFile object. BtrieveFile contains all
  138. the routines for opening and creating files, reading, writing and deleting
  139. records, etc. It contains a pointer to the data buffer that can be
  140. automatically allocated and deallocated by the object if you desire.
  141.  
  142. Next, is the ErrorHandler object, this object controls error handling for the
  143. file. Any Btrieve error may be turned on or off for trapping by the error
  144. handler object. This frees you from the need to check for errors after each
  145. operation, but still allows for full error checking. Each file object has a
  146. pointer to an error handler, this error handler can be the same or different
  147. for each file you open. If an error is turned on the error handler will call
  148. an error display routine, and based on a return code from it, will continue,
  149. abort, or retry an operation.
  150.  
  151. Last, there is the DisplayObject. This object handles the display of any
  152. errors encountered. It is called by the error handler, and returns an action
  153. code, possibly based on some user response, to the error handler.  This
  154. action code will cause the error handler to either abort the program, retry
  155. the operation, or continue processing.
  156.  
  157.  
  158. DECLARATIONS
  159.  
  160. const
  161.   bOpen               = 0;
  162.    ...
  163.   bGetKey             = 50;
  164.  
  165. These constants define all the available btrieve operations.
  166.  
  167.   bOkay               = 0;
  168.    ...
  169.   bLastError          = bOutOfMemory;
  170.  
  171. These define all the status codes returned by Btrieve. In addition there are
  172. constants for file open modes, locking, key types, file flags, etc.
  173.  
  174.   MaxSegments         = 24;
  175.  
  176. Defines the maximum total number of key segments allowed for file. If none of
  177. your files will ever have this many segments then redefine it to some smaller
  178. size and save a few bytes of memory.
  179.  
  180.                                       3
  181. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  182. ──────────────────────────────────────────────────────────────────────────────
  183.   MaxBuffSize         : Word = 16 * 1024;
  184.  
  185. This initialized variable defines the maximum size that will be automatically
  186. allocated for a file data buffer. There is no need to redefine this if you
  187. are using fixed length records, since only as much memory as needed will
  188. actually be allocated. If you are using variable length records and are sure
  189. they will be smaller than 16K bytes, then you can redefine this as needed
  190. before opening the file.
  191.  
  192. {.$DEFINE BCHECK}
  193.  
  194. If this compiler directive is defined a check for Btrieve will be made during
  195. initialization. If it is not present the program will be halted.
  196.  
  197. {.$DEFINE BTRIEVE50}
  198.  
  199. Define this to make all opcodes new to Btrieve version 5.0 available.
  200.  
  201. type
  202.   PProgress = ^TProgress;
  203.   TProgress = Object
  204.     Constructor Init;
  205.     Procedure   Display(Count : LongInt);         Virtual;
  206.   end;
  207.  
  208. Defines an object with a method to display the progress of Recover, Load and
  209. Save operations. Count is the current record count, the display routine will
  210. be called every ten records.
  211.  
  212.   AllErrors     = bInvalidOp..bLastError;
  213.   ErrorSet      = Set of AllErrors;
  214.  
  215. These two define a set of all possible Btrieve errors.
  216.  
  217.   ErrorAction = (erAbort, erDone, erRetry);
  218.  
  219. Enumerates the possible responses to a Btrieve error. One of these three
  220. actions must be returned by your error display routine. If erAbort is
  221. returned the program will be halted, if erDone is returned the program will
  222. continue, if erRetry is returned the Btrieve operation that generated the
  223. error will be executed again.
  224.  
  225.   PErrorDisplay  = ^ErrorDisplay;
  226.   ErrorDisplay   = Object
  227.     Constructor Init;
  228.     Function    Display(Error     : Integer;
  229.                         ErrorMsg  : String;
  230.                         OpCode    : Byte;
  231.                         OpCodeMsg : String;
  232.                         FileName  : PathStr
  233.                         ): ErrorAction;             Virtual;
  234.     Destructor  Done;                               Virtual;
  235.   end;
  236.  
  237. ErrorDisplay is the object that will display errors to the user. This is an
  238. ABSTRACT object and can never be used as is, you must define a descendant
  239.  
  240.                                       4
  241. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  242. ──────────────────────────────────────────────────────────────────────────────
  243. object that does what you want in each program. The error handler will pass
  244. an error number, error description, operation, operation description, and the
  245. full file path to your object. Your object should display the error and
  246. return an action code. This action code can be based on user input, the type
  247. of error, operation or whatever.
  248.  
  249.   PErrorHandler   = ^ErrorHandler;
  250.   ErrorHandler    = Object
  251.     RetryCount    : Word;
  252.     MaxRetry      : Word;
  253.     RetryDelay    : Word;
  254.     TrappedErrors : ErrorSet;
  255.     ErrorDisplay  : PErrorDisplay;
  256.  
  257.     Constructor Init(DisplayObject : PErrorDisplay);
  258.     Function    ErrorDispacther(ErrorCode : Integer;
  259.                                 OpCode    : Byte;
  260.                                 FileName  : PathStr
  261.                                ): ErrorAction;      Virtual;
  262.     Function    Error(Status   : Integer;
  263.                       OpCode   : Byte;
  264.                       FileName : PathStr
  265.                      ): Boolean;                    Virtual;
  266.     Procedure   SetMaxRetry(Retry : Word);
  267.     Function    GetMaxRetry: Word;
  268.     Procedure   SetDelay(Seconds : Word);
  269.     Function    GetDelay: Word;
  270.     Procedure   AddErrors(ErrorCodes : ErrorSet);
  271.     Procedure   RemoveErrors(ErrorCodes : ErrorSet);
  272.     Procedure   SetErrors(ErrorCodes : ErrorSet);
  273.     Procedure   GetErrors(var ErrorCodes : ErrorSet);
  274.     Procedure   ClearRetry;
  275.     Function    ErrorMsg(ErrorCode : Integer): String; Virtual;
  276.     Function    OpMsg(OpCode : Integer): String;    Virtual;
  277.     Destructor  Done;                               Virtual;
  278.   end;
  279.  
  280. This is the error handler object used to trap Btrieve errors. It can be used
  281. as defined. Each possible error can be set so it is trapped or not by this
  282. error handler. By default all errors except end of file are trapped.  All
  283. trapped errors will be routed through the error display object assigned to
  284. the handler when it is initialized. Untrapped errors must be handled directly
  285. in your program code.
  286.  
  287. Locking errors (record in use, file in use) are a special case. These errors,
  288. which happen only on networked systems, automatically generate retries. No
  289. error will be generated until the maximum number of retries, set by you, have
  290. been attempted. This feature can save some programming work on your part if
  291. you are writing an application that uses the networked version of Btrieve.
  292.  
  293. If this all sounds complicated, don't worry, it really isn't that bad. Please
  294. take a look at the example code to see how easy it is to setup the error
  295. handling. My feelings on error checking are that the more automatic it is the
  296. better. In BTV.PAS little work up front leads to considerably less coding
  297. later. You only need to do this stuff once, no matter how many files you
  298. open. Once you get the error handling setup, you can pretty much forget about
  299.  
  300.                                       5
  301. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  302. ──────────────────────────────────────────────────────────────────────────────
  303. it in the rest of your program. In fact, it gets even easier if you create a
  304. standard error handling Unit and reuse in all your programs.
  305.  
  306.   PBtrieveFile  = ^BtrieveFile;
  307.   BtrieveFile   = Object
  308.     Path        : PathStr;
  309.     AltPath     : PathStr;
  310.     Data        : Pointer;
  311.     DataSize    : Integer;
  312.     Allocate    : Boolean;
  313.     BytesRead   : Word;
  314.     BytesToWrite: Word;
  315.     Key         : Pointer;
  316.     KeySize     : Byte;
  317.     SegmentCnt  : Byte;
  318.     CurIndex    : Word;
  319.     IndexCnt    : Byte;
  320.     Status      : Integer;
  321.     FileOpen    : Boolean;
  322.     ErrHandler  : PErrorHandler;
  323.     KeyList     : KeyDefArray;
  324.     KeyStart    : Array[0..MaxSegments - 1] of Byte;
  325.     PosBlock    : Array[1..PosBlockSize] of Byte;
  326.     VariableLen : Boolean;
  327.     SISegments  : Byte;
  328.     ReadKeyDefs : Boolean;
  329.     CurrentKeySize : Byte;
  330.  
  331.     Constructor Init(FilePath    : PathStr;
  332.                      ErrorObject : PErrorHandler;
  333.                      DataBuf     : Pointer;
  334.                      DataBufSize : Word);
  335.     Destructor  Done;                               Virtual;
  336.     Procedure   AddAltSequence(AltSeqPath : PathStr);
  337.     Procedure   AddKeySegment(Position  : Word;
  338.                               Size      : Word;
  339.                               Flags     : Word;
  340.                               KeyType   : Byte;
  341.                               NullValue : Byte;
  342.                               Justify   : Byte);
  343.     Procedure   Open(Mode : Integer;
  344.                      Owner: String);
  345.     Procedure   Close;
  346.     Procedure   Create(Flags      : Word;
  347.                        RecordSize : Word;
  348.                        PageSize   : Word;
  349.                        Pages      : Word;
  350.                        Mode       : Integer);
  351.     Procedure   Clone(NewFilePath : PathStr;
  352.                       Mode        : Integer);
  353.     Function    Error(ErrStatus : Integer;
  354.                       OpCode    : Byte;
  355.                       FileName  : PathStr
  356.                      ): Boolean;
  357.     Function    Recover(NewFilePath : PathStr;
  358.                         DisplayObj  : PProgress): Integer;
  359.  
  360.                                       6
  361. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  362. ──────────────────────────────────────────────────────────────────────────────
  363.     Function    Save(NewFilePath : PathStr;
  364.                      DisplayObj  : PProgress): Integer;
  365.     Function    Load(InputFilePath : PathStr;
  366.                      DisplayObj    : PProgress): Integer;
  367.     Procedure   AddSupplKeySegment(Position  : Word;
  368.                                    Size      : Word;
  369.                                    Flags     : Word;
  370.                                    KeyType   : Byte;
  371.                                    NullValue : Byte;
  372.                                    Justify   : Byte);
  373.     Procedure   CreateIndex;
  374.     Procedure   DropIndex(Index : Integer);
  375.     Procedure   SetOwner(Owner  : String;
  376.                          Mode   : Integer);
  377.     Procedure   ClearOwner;
  378.     Procedure   SetKeyPath(Number : Word);
  379.     Procedure   MakeKey(V1 : Pointer;
  380.                         V2 : Pointer;
  381.                         V3 : Pointer;
  382.                         V4 : Pointer;
  383.                         V5 : Pointer;
  384.                         V6 : Pointer);
  385.     Procedure   Get(Op   : Word;
  386.                     Lock : Word);
  387.     Procedure   GetDirect(Lock     : Word;
  388.                           Position : LongInt);
  389.     Function    GetPosition: LongInt;
  390.     Procedure   UnlockAll(Lock : Word);
  391.     Procedure   Insert;
  392.     Procedure   Update;
  393.     Procedure   SetOutputSize(Size : Word);
  394.     Procedure   AddErrors(ErrorCodes : ErrorSet);
  395.     Procedure   RemoveErrors(ErrorCodes : ErrorSet);
  396.     Procedure   SetErrors(ErrorCodes : ErrorSet);
  397.     Procedure   GetErrors(var ErrorCodes : ErrorSet);
  398.     Procedure   Delete;
  399.     Procedure   ClearBuffer;
  400.     Procedure   ClearKey;
  401.     Procedure   FillKeyBuffer(var KeyBuf; Size : Word);
  402.     Procedure   ChangeBufferSize(Size : Word);
  403.     Procedure   Stat(var FData : FileSpec);
  404.     Function    bResult: Integer;
  405.     Function    IsOpen: Boolean;
  406.     Function    NumberOfRecords: LongInt;
  407.     Procedure   StartTransaction(Lock : Word);
  408.     Procedure   EndTransaction;
  409.     Procedure   AbortTransaction;
  410.     Procedure   Unload;
  411.     Procedure   Reset;
  412.     Procedure   Version(var Ver    : Word;
  413.                         var Rev    : Word;
  414.                         var OSFlag : Char);
  415.     Procedure   FixKeyStrings;
  416.   end;
  417.  
  418. The BtrieveFile object is the heart of BTV.PAS. It contains all the routines
  419.  
  420.                                       7
  421. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  422. ──────────────────────────────────────────────────────────────────────────────
  423. for manipulating Btrieve files. It is a fairly complex object; but, it
  424. greatly simplifies your interaction with Btrieve files.
  425.  
  426. You will create one of these objects for each file you want to access in a
  427. program. To open a file, you execute two object methods. First, you init the
  428. object passing a file path, an error handler (can be nil), and a pointer to a
  429. data buffer and the data buffer size. Any number of files can share a single
  430. error handler. If you pass a nil pointer for the data buffer, a buffer will
  431. be allocated for you. Next, you call Open with an open mode (Read Only,
  432. Exclusive, or Accelerated ) and file owner name.
  433.  
  434. Creating a file is almost as easy. Init is called the same as for Open.
  435. Next, for each key segment needed, you execute the AddKeySegment method
  436. passing the key position, size, key type, etc. This will define each key
  437. segment you need for the file.
  438.  
  439. After all keys are defined make a call to Create. This method takes the file
  440. flags, record size, page size, etc. as parameters and Creates a new file.
  441. Create does not open the file, so finish off with a call to the Open method.
  442.  
  443. Reading and writing records is just as simple. For a read by key you must
  444. first make a call to MakeKey, to build the key buffer. Then call Get,
  445. supplying the opcode for the type of read you want and the locking state. The
  446. data will be passed back in the file buffer setup on initialization. For the
  447. step operation you just call Get passing the correct opcode.
  448.  
  449. To write a new record, fill the buffer you setup and execute the Insert
  450. method. To change a record, first read it with a call to Get. Make any
  451. changes to the buffer and call Update.
  452.  
  453. Procedure CheckForBtrieve;
  454.  
  455. This procedure can be called to check for the presence of Btrieve. It halts
  456. the program if Btrieve is not loaded. This is the same routine called during
  457. program initialization, if that feature is enabled.
  458.  
  459.  
  460. OBJECT DECLARATIONS - BtrieveFile
  461.  
  462.   FIELDS -
  463.  
  464.   Allocate          : Allocate : Boolean;
  465.     This field is set by Init and used by Open and Done. If the data buffer
  466.     pointer passed to Init is nil, Allocate is set to TRUE and file buffer
  467.     memory will automatically be allocated and deallocated.
  468.  
  469.   AltPath           : AltPath : PathStr;
  470.     Holds the name and path of an alternate collating sequence for the file.
  471.  
  472.   BytesRead         : BytesRead : Integer;
  473.     Is the number of bytes input from the file on the last read operation.
  474.  
  475.   BytesToWrite      : BytesToWrite: Integer;
  476.     Holds the number of bytes in the buffer that will be output to the file
  477.     on the next write operation. For fixed length records it defaults to the
  478.     size of the file record and should not be changed. For variable length
  479.  
  480.                                       8
  481. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  482. ──────────────────────────────────────────────────────────────────────────────
  483.     records it should be set before each record is written.
  484.  
  485.   CurIndex          : CurIndex : Word;
  486.     CurIndex is the current Key number (access path) used for the reads and
  487.     writes.
  488.  
  489.   CurrentKeySize    : CurrentKeySize : Byte;
  490.     Used to find the largest key.
  491.  
  492.   Data              : Data : Pointer;
  493.     Points to the file buffer.
  494.  
  495.   DataSize          : DataSize : Integer;
  496.     DataSize is the size of the file buffer pointed to by Data.
  497.  
  498.   ErrHandler        : ErrHandler : PErrorHandler;
  499.     A pointer to the ErrorHandler object that will control all error checking.
  500.     If ErrHandler is nil no error checking is done.
  501.  
  502.   FileOpen          : FileOpen : Boolean;
  503.     Will be set to TRUE if the file is opened successfully.
  504.  
  505.   IndexCount        : IndexCnt : Byte;
  506.     Number of keys in the file.
  507.  
  508.   Key               : Key : Pointer;
  509.     Points to the file key buffer.
  510.  
  511.   KeyList           : KeyList : KeyDefArray;
  512.     Holds a definition record for each key segment in the file.
  513.  
  514.   KeySize           : KeySize : Byte;
  515.     Size of the key buffer pointed to by KeySize.
  516.  
  517.   KeyStart          : KeyStart : Array[0..MaxSegments - 1] of Byte;
  518.     Holds a list of the offsets of the first segment of each key.
  519.  
  520.   Path              : Path : PathStr;
  521.     Path contains the name and path of the file.
  522.  
  523.   PosBlock          : PosBlock : Array[1..PosBlockSize] of Byte;
  524.     The Btrieve position block.
  525.  
  526.   ReadKeyDefs       : ReadKeyDefs : Boolean;
  527.     Indicates whether the key definitions have been setup manually or should
  528.     be read from the file.
  529.  
  530.   SegmentCnt        : SegmentCnt : Byte;
  531.     The total number of segments in all keys.
  532.  
  533.   Status            : Status : Integer;
  534.     The status of the last Btrieve operation.
  535.  
  536.   VariableLen       : VariableLen : Boolean;
  537.     Set to TRUE if the file holds variable length records.
  538.  
  539.  
  540.                                       9
  541. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  542. ──────────────────────────────────────────────────────────────────────────────
  543.   SISegments        : SISegments : Byte;
  544.     Used in setting up a supplemental index.
  545.  
  546.  
  547.   METHODS -
  548.  
  549.   Init              : Constructor Init(    FilePath    : PathStr;
  550.                                        var ErrorObject : PErrorHandler;
  551.                                            DataBuf     : Pointer;
  552.                                            DataBufSize : Word);
  553.     Initializes the file name and path, sets the pointer to the error handler
  554.     object. If ErrorObject is nil no error checking is done, it is all up
  555.     to the programmer in this case. If DataBuf is not nil then Allocate will
  556.     be set to TRUE and memory for the file buffer will be allocated and
  557.     deallocated automatically. If DataBuf is not nil then DataBufSize must be
  558.     the size of the buffer pointed to by DataBuf. If DataBuf is nil then the
  559.     value of DataBufSize is ignored.
  560.  
  561.     See Open, Create, Done, ErrorHandler object.
  562.  
  563.   Done              : Destructor Done; Virtual;
  564.     Disposes of key buffer memory. If Allocate is TRUE, also disposes of the
  565.     file buffer memory.
  566.  
  567.     See Init.
  568.  
  569.   AbortTransaction  : Procedure AbortTransaction;
  570.     Aborts the current Btrieve transaction.
  571.  
  572.     See EndTransaction, StartTransaction.
  573.  
  574.   AddAltSequence    : Procedure AddAltSequence(AltSeqPath : PathStr);
  575.     Defines an alternate collating sequence file that will be loaded and
  576.     passed to Btrieve on a Create. This method only needs to be called before
  577.     Create and if an alternate collating sequence is desired.
  578.  
  579.     See Create.
  580.  
  581.   AddErrors         : Procedure AddErrors(ErrorCodes : ErrorSet);
  582.     Call AddErrors to add a set of error codes to those handled by the file's
  583.     error handler. Use it in conjunction with RemoveErrors to turn an error
  584.     on and off for automatic trapping. AddErrors just makes a call to the
  585.     error handler AddErrors method, so it is here mostly for convenience. You
  586.     could just as well add errors by dereferencing the ErrHandler pointer.
  587.     But this is one of the most often made calls to the error handler.
  588.  
  589.     See RemoveErrors, ErrHandler, GetErrors, SetErrors, TErrorHandler.
  590.  
  591.   AddKeySegment     : Procedure AddKeySegment(Position  : Word;
  592.                                               Size      : Word;
  593.                                               Flags     : Word;
  594.                                               KeyType   : Byte;
  595.                                               NullValue : Byte;
  596.                                               Justify   : Byte);
  597.     AddKeySegment is used to manually define keys for the file. When creating
  598.     a file the keys must be setup by calls to AddKeySegment. Keys do not have
  599.  
  600.                                       10
  601. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  602. ──────────────────────────────────────────────────────────────────────────────
  603.     to be defined before opening a file. On an Open if no calls to
  604.     AddKeySegment have been made, then the key information will be read from
  605.     the file itself.
  606.  
  607.     Except for Justify, the parameters are the same as defined by Btrieve.
  608.     Position is the position of the segment in the file. It is the same as
  609.     Btrieve expects, remember they start at one not zero. Size is the number
  610.     of bytes in the key segment you are defining. Flags are the usual flags
  611.     such as modifiable, duplicate, etc. KeyType can be any valid type
  612.     understood by Btrieve. NullValue will normally be set to zero. Please
  613.     check your Btrieve manual for more information on defining keys.
  614.  
  615.     Justify is a special parameter that makes the use of left and right
  616.     justified key strings simpler. All pascal type strings (Btrieve's
  617.     lstrings) can be automatically padded to the left or right with spaces to
  618.     their defined sizes. If Justify is set to bLJustify a string will be
  619.     padded to it's full length with spaces. If Justify is bRJustify then a
  620.     string key will be left padded to its defined size with spaces. Set
  621.     Justify to bNormal to leave your key strings as passed.
  622.  
  623.     While this padding is not absolutely necessary, it does make strings
  624.     easier to use. Since the same padding is done to the keys used to read
  625.     from or write to the file, you will never need to worry about trailing or
  626.     leading spaces on your string keys.
  627.  
  628.     To define the keys for a file, just make repeated calls to AddKeySegment.
  629.     Make one call for each segment needed. You must make these calls in
  630.     order, just as if you were building the key data buffer directly. Add the
  631.     segments that make up key one first, then the segments for key two, then
  632.     the segments for key three, etc. The segments for each key must also be
  633.     added in order, segment one, segment two, etc. The data will be stored in
  634.     KeyList and passed to Btrieve on a Create.
  635.  
  636.     A typical call would look like  :
  637.  
  638.         F.AddKeySegment(1,10, bModifiable + bExtended, bLstring, 0, False);
  639.  
  640.     This key starts at position 1 in the file, is modifiable, is a lstring
  641.     and is the last segment in its key path, it has a null value of zero, and
  642.     is not right justified.
  643.  
  644.     See the bXXXXX constants, Create.
  645.  
  646.   AddSupplKeySegment: Procedure   AddSupplKeySegment(Position  : Word;
  647.                                                      Size      : Word;
  648.                                                      Flags     : Word;
  649.                                                      KeyType   : Byte;
  650.                                                      NullValue : Byte;
  651.                                                      Justify   : Byte);
  652.     This functions the same as AddKeySegment but is used to define a
  653.     supplemental index. You can only define one key at a time.
  654.  
  655.     See the bXXXXX constants, CreateIndex, AddKeySegment.
  656.  
  657.   bResult           : Function bResult: Integer;
  658.     This function returns the last error status from Btrieve. Unlike the
  659.  
  660.                                       11
  661. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  662. ──────────────────────────────────────────────────────────────────────────────
  663.     Turbo Pascal IoResult function; a call to bResult does not reset the
  664.     status, so multiple calls can be made to this function.
  665.  
  666.   ChangeBufferSize  : Procedure ChangeBufferSize(Size : Word);
  667.     This method should only be used for files with variable length records
  668.     where the file buffer is allocated by the object. Use it in that rare
  669.     instance when you need to change the size of the file buffer.
  670.  
  671.     See Data, Init.
  672.  
  673.   ClearBuffer       : Procedure ClearBuffer;
  674.     Clears the file data buffer, the memory pointed to by the Data field.
  675.  
  676.   ClearKey          : Procedure ClearKey;
  677.     Clears the file key buffer, the memory pointed to by the Key field.
  678.  
  679.   ClearOwner        : Procedure ClearOwner;
  680.     If an owner has been assigned to a file, this method will clear it.  The
  681.     file must be opened before invoking this method.
  682.  
  683.     See SetOwner.
  684.  
  685.   Clone             : Procedure Clone(NewFilePath : PathStr;
  686.                                       Mode        : Integer);
  687.     Clone will create an empty copy of the file on the specified file path.
  688.     Mode indicates whether the file should be over written if it already
  689.     exists.
  690.  
  691.     See the bXXXXX constants.
  692.  
  693.   Close             : Procedure Close;
  694.     Closes an open file.
  695.  
  696.     See Done.
  697.  
  698.   Create            : Procedure Create(Flags      : Word;
  699.                                        RecordSize : Word;
  700.                                        PageSize   : Word;
  701.                                        Pages      : Word;
  702.                                        Mode       : Integer);
  703.     Create a new file. Flags are the normal Btrieve file flags such as
  704.     truncate, variable length, or key only. RecordSize is the file record
  705.     size, or the fixed length portion size for variable length records.
  706.     PageSize is the page size you want for the file; as usual, it must be a
  707.     multiple of 512 bytes, up to 4096 bytes. Pages is the number of pages
  708.     Btrieve should preallocate to the file. Mode indicates whether the file
  709.     should be over written if it already exists. A typical call could be :
  710.  
  711.         F.Create(bNormal, 100, 512, 0, bNoOverWrite);
  712.  
  713.     This file would have no special features like variable length records, is
  714.     100 bytes long, has a 512 byte page size, has no preallocated pages, and
  715.     will not over write an existing file on the same path.
  716.  
  717.     PLEASE NOTE:
  718.     Before calling Create you must define the keys by calls to AddKeySegment.
  719.  
  720.                                       12
  721. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  722. ──────────────────────────────────────────────────────────────────────────────
  723.     See the bXXXXX constants, AddKeySegment, Init.
  724.  
  725.   CreateIndex       : Procedure CreateIndex;
  726.     Adds a new supplemental index to the file. First, you must set up the new
  727.     index by calling AddSupplKeySegment. If you are adding more than one new
  728.     index, create each one separately.
  729.  
  730.     See AddSupplKeySegment.
  731.  
  732.   Delete            : Procedure Delete;
  733.     Deletes the current record from the file. You must have previously read a
  734.     record.
  735.  
  736.     See Get, GetDirect.
  737.  
  738.   DropIndex         : Procedure DropIndex(Index : Integer);
  739.     Removes the supplemental index specified by the parameter Index from the
  740.     file.
  741.  
  742.   EndTransaction    : Procedure EndTransaction;
  743.     Ends the current Btrieve transaction.
  744.  
  745.     See AbortTransaction, StartTransaction.
  746.  
  747.   Error             : Function Error(ErrStatus: Integer;
  748.                                      OpCode   : Byte;
  749.                                      FileName : PathStr
  750.                                     ): Boolean;
  751.     This method is intended mainly for internal use. If the error handler is
  752.     not nil just makes a call to the error handlers Error method.
  753.  
  754.   FillKeyBuffer     : Procedure FillKeyBuffer(var Buff; Size : Byte);
  755.     This method is for copying data directly into the key buffer. Size is the
  756.     number of bytes to copy.
  757.  
  758.   FixKeyStrings     : Procedure FixKeyStrings;
  759.     Justifies all key strings when writing a record. Internal use only.
  760.  
  761.   Get               : Procedure Get(Op   : Word;
  762.                                     Lock : Word);
  763.     Read a record from the file, this file will execute gets or steps.  If
  764.     you are reading by key value, before executing this method you must set
  765.     up the key by calling MakeKey. Op is the type of read to attempt, such as
  766.     equal to the key, greater than the key, less than the key, step first,
  767.     step last, next record, or previous record. Lock is a standard Btrieve
  768.     locking type. Please see your Btrieve manual for more information on
  769.     record locking.
  770.  
  771.     See the bXXXXX constants, MakeKey, SetKeyPath.
  772.  
  773.   GetDirect         : Procedure GetDirect(Lock     : Word;
  774.                                           Position : LongInt);
  775.     Read a record from the file using a record position. Lock is a standard
  776.     Btrieve locking type. Position is the position of the desired record, you
  777.     should get this by a call to GetPosition. You may want to call SetKeyPath
  778.     to establish the index that will be active after the read. Please see
  779.  
  780.                                       13
  781. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  782. ──────────────────────────────────────────────────────────────────────────────
  783.     your Btrieve manual for more information on record locking.
  784.  
  785.     See the bXXXXX constants, GetPosition, SetKeyPath.
  786.  
  787.   GetPosition       : Function GetPosition: LongInt;
  788.     Returns the position of the current record in the file. You must have
  789.     previously read a record. Use the value returned as the position
  790.     parameter to GetDirect.
  791.  
  792.     See Get, GetDirect.
  793.  
  794.   GetErrors         : Procedure GetErrors(var ErrorCodes : ErrorSet);
  795.     Returns the full set of trapped error codes currently set in the
  796.     error handler.
  797.  
  798.     See TrappedErrors, SetErrors, AddErrors, RemoveErrors, bXXXXX constants.
  799.  
  800.   Insert            : Procedure Insert;
  801.     Add a new record to the file. Just fill the file buffer (pointed to by
  802.     Data) and call this method. When writing variable length records be sure
  803.     to set the actual number of bytes of data by a call to SetOutputSize.
  804.  
  805.     See SetOutputSize, Update.
  806.  
  807.   IsOpen            : Function IsOpen: Boolean;
  808.     Returns TRUE if the file is open.
  809.  
  810.   Load              : Function Load(InputFilePath : PathStr;
  811.                                     DisplayObj    : PProgress): Integer;
  812.     Reads records from a DOS file and inserts them into the file. This
  813.     operates the same as BUTIL with the -Load option. The file being read
  814.     must be in the same format as BUTIL generates with the -Recover option.
  815.     Load will read the files generated by the Save method.
  816.  
  817.     InputFilePath is the name of the DOS file to read from. DisplayObj is a
  818.     pointer to a method that can be called to display the progress of Load.
  819.     Recover. DisplayObj can be nil, in that case no call will be made.
  820.  
  821.     Load will return a non-zero value if any errors occur. If there is an
  822.     error, you can check the value of bResult to tell which file had a
  823.     problem. If bResult returns zero, then the DOS file had an error. If the
  824.     error returned is bLoadInputErr, then the DOS file is not in the correct
  825.     format.
  826.  
  827.     See Save.
  828.  
  829.   MakeKey           : Procedure MakeKey(V1 : Pointer;
  830.                                         V2 : Pointer;
  831.                                         V3 : Pointer;
  832.                                         V4 : Pointer;
  833.                                         V5 : Pointer;
  834.                                         V6 : Pointer);
  835.     Use this method to build a key before reading a record. The V1..V6
  836.     parameters are the addresses of the data values that will make up the
  837.     key. These parameters must be specified in the same order as in the key.
  838.     A key will be built for the current index, held in the CurIndex field.
  839.  
  840.                                       14
  841. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  842. ──────────────────────────────────────────────────────────────────────────────
  843.     Any unused parameters should be passed with a value of nil. A typical
  844.     call might be :
  845.  
  846.         F.MakeKey(@State, @City, nil, nil, nil, nil);
  847.  
  848.     You may need to call SetKeyPath to establish the index that you want to
  849.     use.
  850.  
  851.     See the bXXXXX constants, SetKeyPath.
  852.  
  853.   NumberOfRecords   : Function NumberOfRecords: LongInt;
  854.     Returns the NumberOfRecords, actually the largest number of records ever
  855.     in the file, reported by Btrieve.
  856.  
  857.   Open              : Procedure Open(Mode : Integer;
  858.                                      Owner: String);
  859.     Open a file. Mode is the file access mode such as accelerated, exclusive,
  860.     read only or verify. It would normally be set to zero. Owner is the eight
  861.     character file owner name. Unless you have set an owner name with a call
  862.     to SetOwner, this should be a null string.
  863.  
  864.     See the bXXXXX constants, SetOwner, Init.
  865.  
  866.   Recover           : Function Recover(NewFilePath : PathStr;
  867.                                        DisplayObj    : PProgress): Integer;
  868.     Recover Clones the file, then copies all possible records to the new
  869.     file. The file should be opened in Read Only mode.
  870.  
  871.     NewFilePath is the name of the new file to create. DisplayObj is a
  872.     pointer to a method that can be called to display the progress of
  873.     Recover. DisplayObj can be nil, in that case no call will be made.
  874.  
  875.     Recover will return a non-zero value if any errors occur. If there is an
  876.     error, you can check the value of bResult to tell which file had a
  877.     problem. If bResult returns zero, then the new file had an error.
  878.  
  879.   RemoveErrors      : Procedure RemoveErrors(ErrorCodes : ErrorSet);
  880.     Use RemoveErrors to remove a set of error codes from those handled by the
  881.     file's error handler. Use it in conjunction with AddErrors to turn an
  882.     error on and off for automatic trapping. RemoveErrors just makes a call
  883.     to the error handler RemoveErrors method, so it is here mostly for
  884.     convenience. You could just as well remove errors by dereferencing the
  885.     ErrHandler pointer. But this is one of the most often used calls for the
  886.     error handler.
  887.  
  888.     See AddErrors, ErrHandler, TErrorHandler.
  889.  
  890.   Reset             : Procedure Reset;
  891.     Resets all resources held by a workstation.
  892.  
  893.   Save              : Function Save(NewFilePath : PathStr;
  894.                                     DisplayObj    : PProgress): Integer;
  895.     Writes all the records that can be read to a DOS file. The file should be
  896.     opened in Read Only mode. This method operates the same as BUTIL with the
  897.     -Recover option. The file being written is in the same format as BUTIL
  898.     needs for its -Load option.  Save generates file that can be read by the
  899.  
  900.                                       15
  901. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  902. ──────────────────────────────────────────────────────────────────────────────
  903.     Load method.
  904.  
  905.     NewFilePath is the name of the DOS file to create. DisplayObj is a
  906.     pointer to a method that can be called to display the progress of Save.
  907.     DisplayObj can be nil, in that case no call will be made.
  908.  
  909.     Save will return a non-zero value if any errors occur. If there is an
  910.     error, you can check the value of bResult to tell which file had a
  911.     problem. If bResult returns zero, then the DOS file had an error.
  912.  
  913.     See Load.
  914.  
  915.   SetErrors         : Procedure SetErrors(ErrorCodes : ErrorSet);
  916.     Setup the full set of trapped errors currently used by the error handler.
  917.  
  918.     See SetErrors, GetErrors, AddErrors, RemoveErrors, bXXXXX constants.
  919.  
  920.   SetKeyPath        : Procedure SetKeyPath(Number : Word);
  921.     Sets the key number (access path) that will be used for all reads and
  922.     writes.
  923.  
  924.   SetOutputSize     : Procedure SetOutputSize(Size : Word);
  925.     Call SetOutputSize to set the length of the buffer before writing a
  926.     record to the file. This defaults to the size of the record defined in
  927.     the file, so this is used only for variable length records.
  928.  
  929.   SetOwner          : Procedure SetOwner(Owner  : String;
  930.                                          Mode   : Integer);
  931.     Owner is the eight character file owner name. Mode is the restrictions
  932.     desired on access to the file. Please consult your Btrieve manual for
  933.     more information on these restrictions.
  934.  
  935.     See the bXXXXX constants, ClearOwner.
  936.  
  937.   StartTransaction  : Procedure StartTransaction(Lock : Word);
  938.     Start a Btrieve transaction.
  939.  
  940.     See AbortTransaction, StartTransaction.
  941.  
  942.   Stat              : Procedure Stat(var FData : FileSpec);
  943.     Returns the file statistics reported by Btrieve.
  944.  
  945.   Unload            : Procedure Unload;
  946.     Unloads Btrieve from memory.
  947.  
  948.   UnlockAll         : Procedure UnlockAll(Lock : Word);
  949.     Unlocks all locked records in the file. Lock identifies the type of locks
  950.     that are active. Less than or equal to 200 indicates single locks,
  951.     greater than 200 indicates multiple record locks. Please see your Btrieve
  952.     manual for more information on record locking.
  953.  
  954.     See the bXXXXX constants.
  955.  
  956.   Update            : Procedure Update;
  957.     Updates an existing record in the file. When writing variable length
  958.     records be sure to set the actual number of bytes of data by a call to
  959.  
  960.                                       16
  961. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  962. ──────────────────────────────────────────────────────────────────────────────
  963.     SetOutputSize.
  964.  
  965.     See SetOutputSize, Insert.
  966.  
  967.   Version           : Procedure Version(var Ver    : Word;
  968.                                         var Rev    : Word;
  969.                                         var OSFlag : Char);
  970.     Returns the version number of Btrieve that is running. Ver is the full
  971.     version number, Rev is the revision number, OSFlag indicates the
  972.     operating system.
  973.  
  974.  
  975. OBJECT DECLARATIONS - ErrorHandler
  976.  
  977.   FIELDS -
  978.  
  979.   RetryCount        : RetryCount    : Word;
  980.     The number of times an operation has been attempted so far. RetryCount
  981.     is only used on lock errors.
  982.  
  983.   MaxRetry          : MaxRetry      : Word;
  984.     The maximum number of retries allowed.
  985.  
  986.   RetryDelay        : RetryDelay    : Word;
  987.     Delay between retries.
  988.  
  989.   TrappedErrors     : TrappedErrors : ErrorSet;
  990.     Set of all trapped errors. Any error in this set will be checked for by
  991.     ErrorHandler and passed to an error display routine. This set defaults to
  992.     all errors except End Of File.
  993.  
  994.   ErrorDisplay      : ErrorDisplay  : PErrorDisplay;
  995.     Pointer to the object that will be called to display errors. If 
  996.     ErrorDisplay is nil, no errors will be displayed.
  997.  
  998.  
  999.   METHODS -
  1000.  
  1001.   Init              : Constructor Init(var DisplayObject: PErrorDisplay);
  1002.     Initialize the error handler. DisplayObject is the object that will be
  1003.     called to display errors. If DisplayObject is nil, no errors will be 
  1004.     displayed.
  1005.  
  1006.     See Done, ErrorDisplay object.
  1007.  
  1008.   Done              : Destructor Done; Virtual;
  1009.     Destroys the object.
  1010.  
  1011.     See Init.
  1012.  
  1013.   AddErrors         : Procedure AddErrors(ErrorCodes : ErrorSet);
  1014.     Add the errors in the set ErrorCodes to the set of trapped errors.
  1015.  
  1016.     See ErrorSet, TrappedErrors, SetErrors, GetErrors, RemoveErrors,
  1017.     bXXXXX constants.
  1018.  
  1019.  
  1020.                                       17
  1021. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  1022. ──────────────────────────────────────────────────────────────────────────────
  1023.   ClearRetry        : Procedure ClearRetry;
  1024.     Clears the current number of retries.
  1025.  
  1026.     See SetDelay, GetDelay, RetryCount, ClearRetry, MaxRetry, GetMaxRetry.
  1027.  
  1028.   ErrorDispatcher   : Function ErrorDispacther(ErrorCode : Integer;
  1029.                                                OpCode    : Byte;
  1030.                                                FileName  : PathStr
  1031.                                               ): ErrorAction; Virtual;
  1032.     ErrorDispatcher is called by the Error method. The error code, error
  1033.     description, operation code, operation description, and file path name
  1034.     will be passed to the error display object to display and classify.
  1035.  
  1036.     The error object will return an action code, erAbort, erDone, or erRetry.
  1037.     On erAbort the program will be immediately halted. erDone will cause the
  1038.     error state to be cleared, so the operation will return to your program
  1039.     code. erRetry will leave the error state to TRUE, so the operation can be
  1040.     retried.
  1041.  
  1042.     See Error, ErrorDisplay object, ErrorAction, bXXXXX constants.
  1043.  
  1044.   Error             : Function Error(Status   : Integer;
  1045.                                      OpCode   : Byte;
  1046.                                      FileName : PathStr
  1047.                                     ): Boolean; Virtual;
  1048.     If Status is in the set of trapped errors (zero cannot be added to the
  1049.     set), Error calls the ErrorDispatcher method. The status will be passed
  1050.     to the ErrorDisplay object through the ErrorDispatcher routine. In the
  1051.     case of file or record lock errors (84, 85), no error will be generated
  1052.     until the operation has been tried the number of times stored in
  1053.     RetryCount.
  1054.  
  1055.     If the action code returned by the error dispatcher is erDone, Error will
  1056.     return FALSE to the calling routine, indicating no more errors. If the
  1057.     action code is erRetry then TRUE is returned, so the calling routine will
  1058.     execute the operation again.
  1059.  
  1060.     If a Status is not in the set of trapped errors, FALSE is always
  1061.     returned. In this case the program must check the file status for errors.
  1062.  
  1063.     See ErrorDispatcher, ErrorDisplay object, ErrorAction, bXXXXX constants.
  1064.  
  1065.   ErrorMsg          : Function ErrorMsg(ErrorCode : Integer
  1066.                                        ): String; Virtual;
  1067.     Returns a string describing the error associated with ErrorCode.
  1068.  
  1069.     See the bXXXXX constants.
  1070.  
  1071.   GetDelay          : Function GetDelay: Word;
  1072.     Returns the current seconds delay between retries.
  1073.  
  1074.     See GetDelay, RetryCount.
  1075.  
  1076.   GetErrors         : Procedure GetErrors(var ErrorCodes : ErrorSet);
  1077.     Returns the full set of trapped error codes.
  1078.  
  1079.  
  1080.                                       18
  1081. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  1082. ──────────────────────────────────────────────────────────────────────────────
  1083.     See TrappedErrors, SetErrors, AddErrors, RemoveErrors, ErrorSet,
  1084.     bXXXXX constants.
  1085.  
  1086.   GetMaxRetry       : Function GetMaxRetry: Word;
  1087.     Return the maximum number of retries.
  1088.  
  1089.     See RetryCount, ClearRetry, MaxRetry, SetMaxRetry.
  1090.  
  1091.   OpMsg             : Function OpMsg(OpCode : Integer): String; Virtual;
  1092.     Returns a string describing the operation associated with OpCode.
  1093.  
  1094.     See the bXXXXX constants.
  1095.  
  1096.   RemoveErrors      : Procedure RemoveErrors(ErrorCodes : ErrorSet);
  1097.     Remove the errors in the set ErrorCodes from the set of trapped errors.
  1098.  
  1099.     See TrappedErrors, SetErrors, GetErrors, AddErrors, ErrorSet,
  1100.     bXXXXX constants.
  1101.  
  1102.   SetDelay          : Procedure SetDelay(Seconds : Word);
  1103.     Set the seconds of delay between retries. This delay is only used for
  1104.     lock errors.
  1105.  
  1106.     See GetDelay, RetryCount.
  1107.  
  1108.   SetErrors         : Procedure SetErrors(ErrorCodes : ErrorSet);
  1109.     Setup the full set of trapped errors.
  1110.  
  1111.     See SetErrors, GetErrors, AddErrors, RemoveErrors, ErrorSet,
  1112.     bXXXXX constants.
  1113.  
  1114.   SetMaxRetry       : Procedure SetMaxRetry(Retry : Word);
  1115.     Set the maximum number of retries.
  1116.  
  1117.     See RetryCount, ClearRetry, MaxRetry, GetMaxRetry.
  1118.  
  1119.  
  1120. OBJECT DECLARATIONS - ErrorDisplay
  1121.  
  1122.   METHODS -
  1123.  
  1124.   Init              : Constructor Init;
  1125.     Initialize the object;
  1126.  
  1127.     See Done;
  1128.  
  1129.   Display           : Function Display(Error     : Integer;
  1130.                                        ErrorMsg  : String;
  1131.                                        OpCode    : Byte;
  1132.                                        OpCodeMsg : String;
  1133.                                        FileName  : PathStr
  1134.                                        ): ErrorAction; Virtual;
  1135.  
  1136.     This routine is called by the error handler, for any errors that are in
  1137.     the set of trapped errors. Error is the Btrieve status code, ErrorMsg a
  1138.     description of the error code. OpCode is the operation that generated the
  1139.  
  1140.                                       19
  1141. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  1142. ──────────────────────────────────────────────────────────────────────────────
  1143.     error. OpCodeMsg is a description of the operation. FileName is the full
  1144.     path name for the file. This routine must return an action code that will
  1145.     tell the error handler what to do next.
  1146.  
  1147.     Here is an example of a what typical error display method might look
  1148.     like :
  1149.  
  1150.     Function TheErrorDisplay.Display(Error: Integer; ErrorMsg: String;
  1151.                                      OpCode: Byte; OpCodeMsg: String;
  1152.                                      FileName: PathStr): ErrorAction;
  1153.       var
  1154.         Ch : Char;
  1155.       begin
  1156.         GotoXY(1,1);   { show what happened }
  1157.         Writeln('<BTRIEVE IO ERROR>');  Writeln(FileName);
  1158.         Writeln(ErrorMsg);  Writeln(OpCodeMsg);
  1159.  
  1160.         Case Error of   { a couple errors to abort on }
  1161.           bFileNotOpen, bFileNotFound, bNotLoaded :
  1162.           begin
  1163.             Writeln('Press a key ...');
  1164.             Ch := ReadKey;
  1165.             Display := erAbort;
  1166.           end;
  1167.           else  { we will let user decide what to do here }
  1168.           begin
  1169.             Writeln('Do you wish to try again (Y/N)?');
  1170.             Ch := UpCase(ReadKey);
  1171.  
  1172.             if (Ch = 'Y') then Display := erRetry
  1173.             else Display := erDone;
  1174.           end;
  1175.         end;
  1176.       end;
  1177.  
  1178.     As you can see, you have full control of what happens because of any
  1179.     error. You can use the opcode and error to classify errors and control
  1180.     the error handler actions. Pass back erAbort to halt the program, erRetry
  1181.     to make another attempt, or erDone to continue and return the error to
  1182.     your program.
  1183.  
  1184.   Done              : Destructor Done; Virtual;
  1185.     Destroys the object.
  1186.  
  1187.     See Init.
  1188.  
  1189.  
  1190. OBJECT DECLARATIONS - TProgress
  1191.  
  1192.   METHODS -
  1193.  
  1194.   Init              : Constructor Init;
  1195.  
  1196.   Display           : Procedure Display(Count : LongInt);
  1197.     This method is called by Recover, Save, and Load to display the progress
  1198.     of the operation. You must define a new descendant object with a working
  1199.  
  1200.                                       20
  1201. BTV - Turbo Pascal OOP Interface for Btrieve                      Version 1.15
  1202. ──────────────────────────────────────────────────────────────────────────────
  1203.     Display method. Before calling Recover, Save, or Load, initialize an
  1204.     object of your new type. Then pass a pointer to your object to Recover,
  1205.     Save, or Load. Your Display method will be called every ten records plus
  1206.     one final time when the operation is complete.
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.                                       21
  1261. APPENDIX A - bXXXXX Constants
  1262.  
  1263.   The following are Btrieve defined operation codes.
  1264.  
  1265.     bOpen               = 0           bEndTransaction     = 20
  1266.     bClose              = 1           bAbortTransaction   = 21
  1267.     bInsert             = 2           bGetPosition        = 22
  1268.     bUpdate             = 3           bGetDirect          = 23
  1269.     bDelete             = 4           bStepNext           = 24
  1270.     bGetEqual           = 5           bStop               = 25
  1271.     bGetNext            = 6           bVersion            = 26
  1272.     bGetPrev            = 7           bUnlock             = 27
  1273.     bGetGreat           = 8           bReset              = 28
  1274.     bGetGreatEqual      = 9           bSetOwner           = 29
  1275.     bGetLess            = 10          bClearOwner         = 30
  1276.     bGetLessEqual       = 11          bCreateIndex        = 31
  1277.     bGetFirst           = 12          bDropIndex          = 32
  1278.     bGetLast            = 13          bStepFirst          = 33
  1279.     bCreate             = 14          bStepLast           = 34
  1280.     bStat               = 15          bStepPrev           = 35
  1281.     bBeginTransaction   = 19          bGetKey             = 50
  1282.  
  1283.  
  1284.   The following are Btrieve defined status codes.
  1285.  
  1286.     bOkay               = 0           bNullKeypath        = 44
  1287.     bInvalidOp          = 1           bBadKeyFlags        = 45
  1288.     bIOerror            = 2           bFileAccessDenied   = 46
  1289.     bFileNotOpen        = 3           bMaxOpenFiles       = 47
  1290.     bKeyNotFound        = 4           bInvalidAltSequence = 48
  1291.     bDuplicateKey       = 5           bKeyTypeErr         = 49
  1292.     bInvalidKey         = 6           bOwnerIsSet         = 50
  1293.     bDifferentKey       = 7           bInvalidOwner       = 51
  1294.     bInvalidPos         = 8           bCacheWriteErr      = 52
  1295.     bEOF                = 9           bInvalidVersion     = 53
  1296.     bKeyModifyErr       = 10          bVariablePageErr    = 54
  1297.     bInvalidName        = 11          bAutoIncrementErr   = 55
  1298.     bFileNotFound       = 12          bBadIndex           = 56
  1299.     bExtendedFileErr    = 13          bExpandedMemoryErr  = 57
  1300.     bPreImageOpenErr    = 14          bCompressBuffShort  = 58
  1301.     bPreImageIOErr      = 15          bFileExists         = 59
  1302.     bExpansionErr       = 16          bRejectMax          = 60
  1303.     bCloseErr           = 17          bWorkSpaceShort     = 61
  1304.     bDiskFull           = 18          bDescriptorErr      = 62
  1305.     bUnRecoverableErr   = 19          bExtInsertBuffErr   = 63
  1306.     bNotLoaded          = 20          bFilterLimit        = 64
  1307.     bKeyBufferShort     = 21          bFieldOffsetErr     = 65
  1308.     bDataBufferShort    = 22          bTTSabort           = 74
  1309.     bPosBlockShort      = 23          bDeadlock           = 78
  1310.     bPageSizeErr        = 24          bConflict           = 80
  1311.     bCreateIOErr        = 25          bLockErr            = 81
  1312.     bNumberKeys         = 26          bLostPosition       = 82
  1313.     bInvalidKeyPos      = 27          bOutOfTransaction   = 83
  1314.     bRecordLenErr       = 28          bRecordInUse        = 84
  1315.     bKeyLenErr          = 29          bFileInUse          = 85
  1316.     bNotBtrieveFile     = 30          bFileTblFull        = 86
  1317.     bFileExtended       = 31          bHandleTblFull      = 87
  1318.     bExtendIOErr        = 32          bBadModeErr         = 88
  1319.  
  1320.                                       22
  1321.     bExtendNameErr      = 34          bDeviceTableFull    = 90
  1322.     bDirectoryErr       = 35          bServerErr          = 91
  1323.     bTransactionErr     = 36          bTranTableFull      = 92
  1324.     bTransactionActive  = 37          bBadLockType        = 93
  1325.     bTransactionFileErr = 38          bPermissionErr      = 94
  1326.     bTransactionEndErr  = 39          bSessionInvalid     = 95
  1327.     bTransactionMaxFiles= 40          bCommunicationErr   = 96
  1328.     bOpNotAllowed       = 41          bDataMessageShort   = 97
  1329.     bAcceleratedErr     = 42          bInternalTTSerr     = 98
  1330.     bInvalidAddress     = 43
  1331.  
  1332.  
  1333.   The follwing are special BTV.PAS defined errors. Use the constant names,
  1334.   since the numeric value could well change if Novell adds more error
  1335.   codes.
  1336.  
  1337.     bOutOfMemory        = 120
  1338.  
  1339.     Indicates that buffers could not be allocated due to low memory.
  1340.  
  1341.     bDuplicateFilename  = bOutOfMemory + 1
  1342.  
  1343.     The filename passed to Clone, Recover, Save, Load is the same as the
  1344.     file's name.
  1345.  
  1346.     bLoadInputErr       = bDuplicateFilename + 1
  1347.  
  1348.     Something is wrong with the data that Load is trying to read.
  1349.  
  1350.     bLastError          = bLoadInputErr
  1351.  
  1352.     Use if you need the last valid error number for error trapping.
  1353.  
  1354.  
  1355.   The following are BTV.PAS defined constants.
  1356.  
  1357.     bNormal             = 0
  1358.  
  1359.     bRJustify           = 1           bLJustify           = 2
  1360.  
  1361.     These are the two types of key string justifications.
  1362.  
  1363.  
  1364.   The following is a Btrieve defined file create mode.
  1365.  
  1366.     bNoOverWrite        = -1
  1367.  
  1368.  
  1369.   The following are Btrieve defined file owner access modes.
  1370.  
  1371.     bReadAccess         = 1           bReadAccessEncrypt  = 3
  1372.     bWriteAccessEncrypt = 2
  1373.  
  1374.  
  1375.   The following are Btrieve defined file attribute flags.
  1376.  
  1377.     bVariableLen        = 1           bKeyOnly            = 16
  1378.     bBlankTruncate      = 2           b10Free             = 64
  1379.  
  1380.                                       23
  1381.     bPreallocate        = 4           b20Free             = 128
  1382.     bDataCompress       = 8           b30Free             = 192
  1383.  
  1384.   The following are Btrieve defined file open modes.
  1385.  
  1386.     bAccelerated        = -1          bVerify             = -3
  1387.     bReadOnly           = -2          bExclusive          = -4
  1388.  
  1389.  
  1390.   The following are Btrieve defined key attribute flags.
  1391.  
  1392.     bDuplicates         = 1           bAltSequence        = 32
  1393.     bModifiable         = 2           bDescending         = 64
  1394.     bBinary             = 4           bSupplemental       = 128
  1395.     bNull               = 8           bExtended           = 256
  1396.     bSegmented          = 16          bManual             = 512
  1397.  
  1398.  
  1399.   The following are Btrieve defined key types.
  1400.  
  1401.     bString             = 0           bLogical            = 7
  1402.     bInteger            = 1           bNumeric            = 8
  1403.     bFloat              = 2           bBfloat             = 9
  1404.     bDate               = 3           bLstring            = 10
  1405.     bTime               = 4           bZstring            = 11
  1406.     bDecimal            = 5           bUnsigned           = 14
  1407.     bMoney              = 6           bAutoIncrement      = 15
  1408.  
  1409.  
  1410.   The following are Btrieve defined lock types.
  1411.  
  1412.     bNoLock             = 0           bMultipleWait       = 300
  1413.     bSingleWait         = 100         bMultipleNoWait     = 400
  1414.     bSingleNoWait       = 200
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.                                       24
  1441. APPENDIX B - Revision History and Notes
  1442.  
  1443.   Date    Ver   What                                                      
  1444. ============================================================================= 
  1445. 02/01/92  1.01  Changed DataSize, BytesRead, BytesToWrite from Integer to 
  1446.                 Word so variable length records can be up to 64K.         
  1447.  
  1448. 02/04/92        Check that memory allocation size > 0 before issuing an   
  1449.                 out of memory error.                                      
  1450.  
  1451.                 Added ErrorHandler calls for out of memory errors.        
  1452.  
  1453. 02/08/92        Added error setting routines to the file object, so calls 
  1454.                 through the error handler object pointer are not needed.  
  1455.  
  1456. 02/20/92        Fixed bug in Clone. Wrong file name being used caused     
  1457.                 lockup.                                                   
  1458.  
  1459. 02/28/92  1.10  Added Recover, Save and Load methods.                     
  1460.  
  1461. 03/14/92  1.11  Open was not calculating the largest key correctly.       
  1462.  
  1463. 04/25/92  1.15  Added the FillKeyBuffer method.                           
  1464.  
  1465. 05/13/92        Fixed problem with KeyStart buffer not being setup when   
  1466.                 key segments not defined before opening a file.           
  1467.  
  1468.                 Changed Error Handler and Error Display in fields in all  
  1469.                 objects, and the corresponding parameters in methods, to  
  1470.                 pointers. This allows nil error objects. 
  1471.  
  1472.                 PLEASE NOTE : This change will cause a type mismatch when
  1473.                 you recompile. Just stick a "@" before any error object 
  1474.                 parameters and try it again.
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.                                       25